Introduce JKlib entry point #5558

nikita-nazarov · 2025-11-12T14:51:00Z

This PR is a preliminary version of the Kotlin compiler entry point for J2CL.
Currently there is a lot of mocking going around and there are a couple of workarounds introduced, so I believe some of the Kotlin API has to be modified to make this code cleaner. But anyway this PR should give you an impression of what we would like to achieve.

The ultimate goal would be to put this extension point in the Kotlin compiler repo together with some IR text tests, so that it would be possible to catch bugs early and to perform the required API migrations as fast as possible.

Here is a link to the related document.

Context

Currently, to transpile Kotlin code, J2CL acts as a compiler plugin. It is facing challenges in inlining Kotlin functions due to its reliance on the experimental and unsupported -Xserialize-ir compiler flag to serialize the IR of a library in its corresponding header JAR file. This approach has led to issues such as orphaned IR nodes and incomplete IR serialization, particularly in complex scenarios like transitive inline calls. Additionally, compiling the standard library (stdlib) with this flag has presented further complications.These issues needed to be addressed before the wider adoption of J2CL’s Kotlin frontend. In that context, the Kotlin compiler team at JetBrains proposed the following solution that relies on klibs.

The Klib pipeline

With this extension point J2CL transpilation happens roughly the following way:

Given a set of source files and jar and klib dependencies, compile the source module to a klib (using K2 frontend).
Deserialise the klib (using K1) and link the IR, then give the resulting IR to J2CL.
At J2CL run custom IR lowerings
Perform the finalised IR -> Closure transpilation

Workarounds

When trying to implement this klib based pipeline we have encountered numerous issues (kudos to @kunyavskiy to help us fix them!), which made us introduce a couple of workarounds that are best described in this document:

Instead of writing Kotlin signatures of imported Java functions to a klib, we write plain Java signatures to address signature mismatches between K1 and K2.
For example given this code:

fun <T, U : Comparable<U>> Comparator<T>.foo(
  keyExtractor: Function<in T, out U>
): Comparator<T> =
  thenComparing(keyExtractor)

The imported thenComparing function will have different signatures when serializing to klib with K2, and when deserializing with K1:

thenComparing(...){0§<kotlin.Comparable<in|0:0?>?>} // K2 view
thenComparing(...){0§<kotlin.Comparable<0:0?>?>} // K1 view

To fix this issue, we put this signature to a klib:

// Imported signatures:
java/util/Comparator.thenComparing(Ljava/util/function/Function;)Ljava/util/Comparator;

When deserializing Java method signatures of a mapped type, e.g.:

// Imported signatures:
kotlin/Throwable.getSuppressed|getSuppressed(){}[0]

We encountered issues when trying to resolve this declaration, because kotlin.Throwable doesn't define getSuppressed in source code. This method comes from the corresponding java.lang.Throwable class. This made us introduce this workaround, which caches the IR symbols of Java declarations of mapped types.

nikita-nazarov · 2025-11-12T14:53:42Z

compiler/cli/src/org/jetbrains/kotlin/cli/jklib/JKlibMangleComputer.kt

+import org.jetbrains.kotlin.types.model.*
+import org.jetbrains.kotlin.types.typeUtil.isUnit
+
+/*


The entire file is copy pasted from the corresponding Kotlin counterparts, except for the mangleTypeArgumentsUsingEffectiveVariance methods. This is needed to allow always using effective variance during mangling like mentioned in this comment .

nikita-nazarov · 2025-11-12T14:56:14Z

compiler/cli/src/org/jetbrains/kotlin/cli/jklib/JKlibMangler.kt

+import org.jetbrains.kotlin.types.checker.SimpleClassicTypeSystemContext
+import org.jetbrains.kotlin.types.typeUtil.replaceAnnotations
+
+/*


Most of the file is copied. The difference is in the signatureString methods that yield JVM signatures for Java methods.

nikita-nazarov · 2025-11-12T15:00:52Z

compiler/cli/src/org/jetbrains/kotlin/cli/jklib/JKlibMangler.kt

+            && descriptor !is PropertyGetterDescriptor
+}
+
+fun FunctionDescriptor.computeJvmDescriptor(withReturnType: Boolean = true, withName: Boolean = true): String = buildString {


This function is mostly copied from org.jetbrains.kotlin.load.kotlin.MethodSignatureMappingKt#computeJvmDescriptor, except for the workaround described in the comment below.

nikita-nazarov · 2025-11-12T15:02:47Z

compiler/cli/src/org/jetbrains/kotlin/cli/jklib/JKlibMangler.kt

+
+    signature(
+        classDescriptor,
+        (original as? FunctionDescriptor ?: return null).computeJvmDescriptor()


This is the only different line from org.jetbrains.kotlin.load.kotlin.MethodSignatureMappingKt#computeJvmSignature. The original:

(original as? SimpleFunctionDescriptor ?: return null).computeJvmDescriptor()

Just in case, the original function FunctionDescriptor.computeJvmDescriptor seems like some ad-hoc implementation that is only suitable for some specific purpose, and it would be risky to use it to compute JVM signatures of arbitrary declarations. For example, it doesn't support @JvmName, context parameters, constructors of inner/inline/sealed classes, and probably a lot more.

nikita-nazarov · 2025-11-12T15:03:33Z